/**
 * Software License, Version 1.0
 * 
 * Copyright 2003 The Trustees of Indiana University.  All rights reserved.
 * 
 *
 *Redistribution and use in source and binary forms, with or without 
 *modification, are permitted provided that the following conditions are met:
 *
 *1) All redistributions of source code must retain the above copyright notice,
 * the list of authors in the original source code, this list of conditions and
 * the disclaimer listed in this license;
 *2) All redistributions in binary form must reproduce the above copyright 
 * notice, this list of conditions and the disclaimer listed in this license in
 * the documentation and/or other materials provided with the distribution;
 *3) Any documentation included with all redistributions must include the 
 * following acknowledgement:
 *
 *"This product includes software developed by the Community Grids Lab. For 
 * further information contact the Community Grids Lab at 
 * http://communitygrids.iu.edu/."
 *
 * Alternatively, this acknowledgement may appear in the software itself, and 
 * wherever such third-party acknowledgments normally appear.
 * 
 *4) The name Indiana University or Community Grids Lab or NaradaBrokering, 
 * shall not be used to endorse or promote products derived from this software 
 * without prior written permission from Indiana University.  For written 
 * permission, please contact the Advanced Research and Technology Institute 
 * ("ARTI") at 351 West 10th Street, Indianapolis, Indiana 46202.
 *5) Products derived from this software may not be called NaradaBrokering, 
 * nor may Indiana University or Community Grids Lab or NaradaBrokering appear
 * in their name, without prior written permission of ARTI.
 * 
 *
 * Indiana University provides no reassurances that the source code provided 
 * does not infringe the patent or any other intellectual property rights of 
 * any other entity.  Indiana University disclaims any liability to any 
 * recipient for claims brought by any other entity based on infringement of 
 * intellectual property rights or otherwise.  
 *
 *LICENSEE UNDERSTANDS THAT SOFTWARE IS PROVIDED "AS IS" FOR WHICH NO 
 *WARRANTIES AS TO CAPABILITIES OR ACCURACY ARE MADE. INDIANA UNIVERSITY GIVES
 *NO WARRANTIES AND MAKES NO REPRESENTATION THAT SOFTWARE IS FREE OF 
 *INFRINGEMENT OF THIRD PARTY PATENT, COPYRIGHT, OR OTHER PROPRIETARY RIGHTS. 
 *INDIANA UNIVERSITY MAKES NO WARRANTIES THAT SOFTWARE IS FREE FROM "BUGS", 
 *"VIRUSES", "TROJAN HORSES", "TRAP DOORS", "WORMS", OR OTHER HARMFUL CODE.  
 *LICENSEE ASSUMES THE ENTIRE RISK AS TO THE PERFORMANCE OF SOFTWARE AND/OR 
 *ASSOCIATED MATERIALS, AND TO THE PERFORMANCE AND VALIDITY OF INFORMATION 
 *GENERATED USING SOFTWARE.
 */
package cgl.narada.service.buffering;

import cgl.narada.service.ServiceException;
import cgl.narada.service.qos.QosEvent;

/** 
    This interface encapsulates all the functiones needed by the buffering
    service. The buffering service provides a time based ordering of events
    timestamped by the NB Timing Service. 

    @author Shrideep Pallickara and Hasan Bulut
    $Date$
    $Revision$
*/

public interface BufferingService {
  
  /** Sets the scheme for sorting events in the buffers */
  public void setSortingScheme(String sortAlgo) throws ServiceException;
  
  /** Returns the current sorting scheme */
  public String getSortingScheme();

  /** Sets the maximum number of entries in the buffering service. This method
      throws an exception if the specified value is an invalid one 
      (0 or negative). */
  public void setMaximumNumberOfEntries(int maxEntries) 
    throws ServiceException;
  
  /** Returns the maximum number of entries */
  public int getMaximumNumberOfEntries(); 


  /** Release facotr is a double number between 0 - 1. It should not be less
   * than 0.5. the default value is 1.0. Setting this factor to another value
   * causes BufferHandler to release (factor * number of buffer entries)    */
  public void setReleaseFactor(double factor);

  
  /** Returns the release factor of the buffer*/
  public double getReleaseFactor();

  /** Ensures that events are ordered while enforcing timing consistencies. The
      consistencies are enforced based on the timestamp of the last event that
      was released. This has to be EXPLICTLY set. 
   */
  public void 
  setEnforceTimeOrderingConsistency(Object contentSynopsis, boolean enforce);

  /** Indicates if the buffering service enforces time ordering conistency */
  public boolean getEnforceTimeOrderingConsistency(Object contentSynopsis);
  

  /** Sets the maximum buffer size. This corresponds to the total size of all
      the payloads associated with events in the buffer. This method throws an
      exception if the specified value is an invalid one */
  public void setMaximumBufferSize(int maxBufferSize) 
    throws ServiceException;

  
  /** Returns maximum buffer size.This corresponds to the total size of all
      the payloads associated with events in the buffer. */
  public int getMaximumBufferSize();
  
  /** Sets the maximum duration after which the oldest element in the buffer
      is released */
  public void setBufferEntryMaximumDuration(long entryAge);

  /** Retrieves the maximum duration after which the oldest element in the 
      buffer is released 
  public long getBufferEntryMaximumDuration();

  /** Returns the total number of entries currently present within the buffer*/
  public int getTotalNumberOfEntries();

  /** Returns the total size of the buffer. This corresponds to the total size
      of the content payloads of all the events within the buffer */
  public int getTotalBufferSize();

  /** Releases all the entries currently present in the buffer. Returns the 
      total number of entries that were released. */
  public int releaseAllEntries();

  /** Releases all the entries with the specified content synopsis. 
      Returns the total number of entries that were released. */
  public int releaseAllEntries(Object contentSynopsis);

  
  /** Releases all entries that occured before the specified timestamp. 
      Returns the total number of entries that were released. */
  public int releaseAllEntries(long timestamp);

  /** Takes QosEvent and puts it into the buffer. If maximum number of entries
      and/or maximum buffer size is/are reached, it notifies the BufferHandler
      thread. */
  public void timeOrderEvent(QosEvent qosEvent);

  public void terminateService() throws ServiceException;
}
